Interface Definition Language(OD Cookbook)

Inside Macintosh: OpenDoc Cookbook / Part - Appendixes: Appendix B - System Object Model

Interface Definition Language
The SOM Interface Definition Language describes the interface of a SOM object in a set of declarations. Generally, these declarations can specify constants, type of the object, attributes (instance variables), operations (methods), exceptions, and module (which scopes the object).
In SOM, the runtime entities that provide services to clients are always objects, which contain methods and instance variables (also called fields or attributes). Client programs can call the methods to request whatever services the object provides, and the object uses its instance variables to store its state information. The interface to the object, which is expressed in IDL, describes what clients must know to use the object's services. Every SOM object is an instance of a single SOM class, but the implementation language of the object need not support the class concept.

The SOM Interface of SamplePart
The OpenDoc class that represents a part editor is named ODPart. It is a SOM class, as are all the classes in the OpenDoc class library. All part editors are built around a subclass of ODPart. The SamplePart part editor, however, incorporates a scheme by which the part's SOM interface is largely hidden from the programmer.
SamplePart has only one SOM class, a subclass of ODPart named som_SamplePart, referred to as the SOM wrapper class. This SOM class overrides all ODPart methods, although SamplePart implements only some of them. For those methods that SamplePart implements, the SOM wrapper class methods delegate the implementation to a C++ class named som_SamplePart.
The SOM class som_SamplePart is defined in IDL. The SOM class methods merely call corresponding methods in the C++ class, which is named SamplePart. For ODPart methods that SamplePart does not implement, the SOM class override method bodies are empty. They are provided so that you can extend SamplePart simply by adding a call to a method in a C++ class. Therefore, you do not need to revise the SOM class IDL interfaces and use the SOM compiler to extend SamplePart.
The remainder of this appendix describes the artifacts of IDL that appear in the definition of som_SamplePart class in the file som_SamplePart.idl.

The Class Definition
SOM provides a scoping mechanism to group objects into modules; the definition of the SamplePart class declares it to belong to the SampleCode module. The interface statement of the som_SamplePart object shows that it inherits from ODPart. Listing B-1 shows the interface statement.
Listing B-1 Interface statement
module SampleCode
{
   interface som_SamplePart : ODPart
   {
The next part of the interface definition is the implementation section, which is protected by an #ifdef __SOMIDL__ compiler directive to maintain compatibility with pre-SOM versions of IDL. The majorversion and minorversion statements specify a combined version number which the SOM compiler can use to ensure compatibility among different versions of the som_SamplePart class. The functionprefix identifier customizes the names of the implementation functions in the .cpp file. Next, the definition lists all of the methods that som_SamplePart overrides.
Listing B-2 shows the beginning of the implementation section.
Listing B-2 Implementation section
majorversion = 1; minorversion = 0;

functionprefix = som_SamplePart__;
override:
//# ODObject methods
somInit,
somUninit,
AcquireExtension,
HasExtension,
Purge,
ReleaseExtension,
//# ODRefCountedObject methods
Release,
//# ODPersistentObject methods.
CloneInto,
Externalize,
ReleaseAll,

//# ODPart methods
AbortRelinquishFocus,
AcquireContainingPartProperties,
AdjustBorderShape,
...
The final portion of the implementation section, which is private to the som_SamplePart object, contains two parts: a passthru statement and declarations for the som_SamplePart object's instance variable. The passthru statement directs the SOM compiler to write specified information directly into a specified output file. In this case, the information is a forward declaration for the class type SamplePart, which is required by the C++ compiler that will process the output file. The passthru statement specifies the output file to be the implementation binding file with extension .xih. The declaration of the som_SamplePart object's instance variable follows, specifying the variable's data type and identifier.
Listing B-3 shows the final portion of the som_SamplePart class interface definition.
Listing B-3 Last section of the som_SamplePart class definition
#ifdef __PRIVATE__
         passthru C_xih =
            "class SamplePart;";
      
         SamplePart* fPart;
      
#endif //__PRIVATE__
      };
      
#endif //__SOMIDL__
   };
};
SOM class definitions can also include a releaseorder statement to maintain binary compatibility for the SOM class, although som_SamplePart does not need or use the feature. The releaseorder statement specifies the order in which the SOM compiler must incorporate the methods in the class's data structure. The releaseorder specification appears in a private form, protected by an #ifdef __PRIVATE__ compiler directive and a public form for clients, which reserves space for the correct number of methods without naming them. Listing B-4 shows an example of a releaseorder statement.
Listing B-4 releaseorder statement
   releaseorder:
#ifdef __PRIVATE__
      method1, method2, method3;
#else
      reserved1, reserved2, reserved3;
Implementation Template
The SOM compiler generates an implementation template for each method declared in a SOM class. You must fill in the complete implementation for each method in your class. The SOM compiler puts certain macro invocations and other artifacts into these stub method definitions, which you can see by examining the emitted implementation template file (extension .cpp).

Define and Include Directives
Because the implementation template file is the primary source file for the SOM object declared in the corresponding IDL file, the SOM compiler generates a compiler symbol specifying the module name (if any is declared in the IDL specification), the class name, and the words Class_Source, all separated by underscore characters. This directive forces a one-to-one correspondence between the IDL class specification and its implementation.
Listing B-5 shows the som_SamplePart class source define directive.
Listing B-5 Class source define directive
#define SampleCode_som_SamplePart_Class_Source
The include directives in the implementation template file include the implementation binding or private header file (extension .xih) only for the same class whose implementation file this is. The private implementation file is generated by the SOM compiler. It contains macros that give access to instance variables and invoke superclass methods.
Include directives for other SOM classes used in the implementation code include the usage binding or public header file (extension .xh) generated for those classes. For non-SOM classes defined in C++, such as SamplePart, the implementation template file includes the regular C++ header file (extension .h).

Function Prototype
The prototype of each stub method definition generated by the SOM compiler includes several symbols defined in the implementation binding file. Generally, you do not need to worry about these symbols because the SOM compiler simply does the right thing.
Listing B-6 shows a typical SOM-generated function prototype with parameter list that appears in the som_SamplePart implementation template file.
Listing B-6 Typical SOM function prototype
SOM_Scope   void
SOMLINK     som_SamplePart__InitPart
         (
            SampleCode_som_SamplePart*    somSelf,
            Environment*                  ev,
            ODStorageUnit*                storageUnit,
            ODPartWrapper*                partWrapper
               )
The symbol SOM_Scope is defined in the implementation binding file as extern C to generate correct language bindings with parameters in the proper order. The term void is the return value of the method. The symbol SOMLINK is defined by SOM; it is a preprocessor directive to help the linker, and its value is system specific. The method name appears next appended to its function prefix value, which is defined in the IDL file, as som_SamplePart__. The parameter list is described in the following section.

Parameter List
The stub function implementations include two standard parameters in every signature: the self-pointing parameter and the environment parameter. The IDL descriptions of some SOM classes also include a context specification, causing a third standard parameter to be generated, but it does not appear in som_SamplePart. Other parameters are specific to the individual method.
The self-pointing parameter is a pointer to the object that responds to the method call. This parameter is required for implementation languages having no concept of objects, such as C. To call a SOM object's method from C, you must pass the object pointer as the first argument of the calling syntax. From C++, however, you specify the object with the method call in the standard C++ manner (such as myPart->Externalize). The name for this parameter is always somSelf, a convention upon which the macros in the implementation binding file rely.
The environment parameter is a pointer to the environment data structure defined by CORBA. (CORBA stands for Common Object Request Broker Architecture, an interface standard promulgated by the Object Management Group industry consortium.) The environment structure passes exception information between the caller and the called method.

Default Method Calls
By default, every stub method includes three statements. Listing B-7 shows the default statements that appear in the som_SamplePart object's InitPart method definition.
Listing B-7 Stub method default statements
SampleCode_som_SamplePartData *somThis = 
                  SampleCode_som_SamplePartGetData(somSelf);
SampleCode_som_SamplePartMethodDebug("SampleCode_som_SamplePart",
                  "som_SamplePart__InitPart");
SampleCode_som_SamplePart_parent_ODPart_InitPart(somSelf,ev,
                  storageUnit,partWrapper);
The first statement initializes a local pointer variable named somThis that provides access to the instance variables (or attributes) of the class. The somThis variable points to a SOM-generated data structure representing the instance variables, which has a type created by appending the word Data to the class name. Macros in the implementation binding file depend on the somThis variable to create getter and setter methods for each instance variable.
The second of the three default statements aids debugging. It depends on the SampleCode_som_SamplePartMethodDebug macro defined in the implementation binding file. If the SOM global variable SOM_TraceLevel is set to 1 in the client program, this macro produces a debugging message each time the method executes.
The third default statement is a macro that invokes the inherited superclass method of the same name. This statement is generated only for overridden methods. As you fill in the function body of each method, you should delete this statement or place it appropriately in your code: before or after the actions you take in your override.